function
<new>
operator delete[]
ordinary (1) | void operator delete[] (void* ptr) throw(); |
---|
nothrow (2) | void operator delete[] (void* ptr, const std::nothrow_t& nothrow_constant) throw(); |
---|
placement (3) | void operator delete[] (void* ptr, void* voidptr2) throw(); |
---|
ordinary (1) | void operator delete[] (void* ptr) noexcept; |
---|
nothrow (2) | void operator delete[] (void* ptr, const std::nothrow_t& nothrow_constant) noexcept; |
---|
placement (3) | void operator delete[] (void* ptr, void* voidptr2) noexcept; |
---|
ordinary (1) | void operator delete[] (void* ptr) noexcept; |
---|
nothrow (2) | void operator delete[] (void* ptr, const std::nothrow_t& nothrow_constant) noexcept; |
---|
placement (3) | void operator delete[] (void* ptr, void* voidptr2) noexcept; |
---|
with size (4) | void operator delete[] (void* ptr, std::size_t size) noexcept; |
---|
nothrow with size (5) | void operator delete[] (void* ptr, std::size_t size, const std::nothrow_t& nothrow_constant) noexcept; |
---|
Deallocate storage space of array
Default deallocation functions (array form).
- (1) ordinary delete
-
Deallocates the memory block pointed to by ptr (if not null), releasing the storage space previously allocated to it by a call to operator new[] and rendering that pointer location invalid.
- (2) nothrow delete
-
Same as above (1).
- (3) placement delete
-
Does nothing.
- (1) ordinary delete
-
Deallocates the memory block pointed to by ptr (if not null), releasing the storage space previously allocated to it by a call to operator new[] and rendering that pointer location invalid.
The default definition calls ::operator delete(ptr)
.
- (2) nothrow delete
-
Same as above (1).
The default definition calls the first version (1): ::operator delete[](ptr)
.
- (3) placement delete
-
Does nothing.
- (1) ordinary delete
-
Deallocates the memory block pointed to by ptr (if not null), releasing the storage space previously allocated to it by a call to operator new[] and rendering that pointer location invalid.
The default definition calls ::operator delete(ptr)
.
- (2) nothrow delete
-
Same as above (1).
The default definition calls the first version (1): ::operator delete[](ptr)
.
- (3) placement delete
-
Does nothing.
- (4) (5) with size
-
Same as (1) and (2) respectivelly.
The default definition simply calls the corresponding version: either (1) or (2).
They provide an optimization point for custom implementations: they are called with the same size argument used in the call to the corresponding operator new[]|allocation function.
The default allocation and deallocation functions are special components of the standard library; They have the following unique properties:
- Global: All three versions of
operator delete[]
are declared in the global namespace, not within the std namespace.
- Implicit: The deallocating versions (i.e., all but (3)) are implicitly declared in every translation unit of a C++ program, no matter whether header
<new>
is included or not.
- Replaceable: The deallocating versions (i.e., all but (3)) are also replaceable: A program may provide its own definition that replaces the one provided by default to produce the result described above, or can overload it for specific types.
operator delete[]
is a regular function that can be called explicitly just as any other function. But in C++, delete[]
is an operator with a very specific behavior: An expression with the delete[]
operator, first calls the appropriate destructors for each element in the array (if these are of a class type), and then calls an array deallocation function.
The array deallocation function for a class object is a member function named operator delete[]
, if it exists. In all other cases it is a global function operator delete[]
(i.e., this function -- or a more specific overload). If the delete[]
expression is preceded by the scope operator (i.e., ::operator delete[]
), only global array deallocation functions are considered.
delete[]
expressions that use global array deallocation functions, always call single-argument signatures (such as (1)).
delete[]
expressions that use global array deallocation functions always use the signature that takes either a pointer (such as (1)), or a pointer and a size (such as (4)). Preferring always the version with size (4), unless an overload provides a better match for the pointer type.
The other signatures ((2) and (3)) are never called by a delete[]-expression (the delete[]
operator always calls the ordinary version of this function, and exactly once for each of its arguments). These other signatures are only called automatically by a new[]-expression when their object construction fails (e.g., if the constructor of an object throws while being constructed by a new[]-expression with nothrow, the matching operator delete[] function accepting a nothrow argument is called).
Non-member array deallocation functions shall not be declared in a namespace scope other than the global namespace.
Parameters
- ptr
- A pointer to the memory block to be released, type-casted to a
void*
.
If this is a null-pointer, the function does nothing.
Otherwise, this pointer value should have been returned by a previous call to operator new[]
, and have not yet been released by a previous call to this function.
Otherwise, this pointer value should have been returned by a previous call to
operator new[]
, and have not yet been released by a previous call to this function.
If the implementation has
strict pointer safety, this pointer shall also be a
safely-derived pointer.
- nothrow_constant
- The constant nothrow. This parameter is ignored in the default definition.
nothrow_t is the type of constant nothrow.
- voidptr2
- A void pointer. The value is ignored in the default definition.
size
The first argument passed to the allocation function when the memory block was allocated.
std::size_t is an unsigned integral type.
Example
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16
|
// operator delete[] example
#include <iostream> // std::cout
struct MyClass {
MyClass() {std::cout <<"MyClass constructed\n";}
~MyClass() {std::cout <<"MyClass destroyed\n";}
};
int main () {
MyClass * pt;
pt = new MyClass[3];
delete[] pt;
return 0;
}
|
Output:
myclass constructed
myclass constructed
myclass constructed
myclass destroyed
myclass destroyed
myclass destroyed
|
Data races
Modifies the storage referenced by ptr.
Calls to allocation and deallocation functions that reuse the same unit of storage shall occur in a single total order where each deallocation happens before the next allocation.
This shall also apply to the observable behavior of custom replacements for this function.
Exception safety
No-throw guarantee: this function never throws exceptions.
Notice that an invalid value of ptr causes undefined behavior.
Notice that either an invalid value of
ptr, or a value for
size that does not match the one passed to the
allocation function, causes undefined behavior.